Introduction

Who should read this Guide?

This Users' Guide is for Python programmers. Part I is a tutorial/reference and should be read by everybody. Part II is a cookbook of of techniques for using Cheetah with various web frameworks and various non-HTML output formats, plus some technical appendices. The PDF version of this Guide is distributed as two files so you can print Part I to read offline without having to print a lot of pages from Part II that don't apply to you.

What is Cheetah?

Cheetah is a template engine for Python. A template engine is like Python's % operator for strings: it has fixed parts which are output verbatim, and placeholders which are replaced by their values:

# Python's "%" operator (not Cheetah)
>>> "The king is a %(noun)s!" % {"noun": "fink"}
'The king is a fink!"

Templates are useful for form letters, dynamic web pages, customized source code or SQL, and innumerable other tasks. Cheetah is like a super-powered % operator, but it also has many other features needed in real-world templating situations.

Viewed another way, Cheetah is an alternate source format for Python modules, one that's friendlier for large chunks of text. Compiled templates are ordinary Python modules which can be imported. Cheetah is one of Python's oldest template engines and perhaps the most widely used. This is mainly due to its speed (hence the name Cheetah), stability, and suitability for many output formats. Cheetah has been used in production environments since 2001 (0.9.9a1), and changes are committed conservatively, so even the CVS version is usually more bug-free than the previous release.

Cheetah's syntax uses $ before placeholders and a # before control structures (directives), although these characters can be changed. This differs from Python's other template systems which generally use XML tags (Kid and Tal) or a function syntax (PTL and QPY). The difference allows Cheetah to be more suitable for a variety of output formats, and even users of the other systems often use Cheetah for non-HTML output such as text, Python source code, or SQL. Cheetah's syntax and behavior was inspired most directly by Velocity, a Java template engine. In PHP, Smarty is Cheetah's closest equivalent. Cheetah templates tend to be function-driven: define a method with #def, and call it via a placeholder with arguments. Cheetah also has PSP-style tags (<% %>) and #include, which will be familiar to people coming from ASP/JSP/PHP. However, we'll argue that these should be used sparingly, since there are other constructs which are more readable.

Cheetah:

Here's a simple example of a Cheetah template:

<HTML>
<HEAD><TITLE>$title</TITLE></HEAD>
<BODY>

<TABLE>
#for client in clients
<TR>
<TD>$client.surname, $client.firstname</TD>
<TD><A HREF="mailto:$client.email">$client.email</A></TD>
</TR>
#end for
</TABLE>

</BODY>
</HTML>

Cheetah is distributed under a BSD-style open-source license. See appendix E (E_license.txt) for details. Cheetah exists thanks to the help of many open-source volunteers (http://cheetahtemplate.sourceforge.net/credits.html).

What is the philosophy behind Cheetah?

Cheetah's design was guided by these principles:

Why Cheetah doesn't use HTML-style tags

Cheetah does not use HTML/XML-style tags for flow control, unlike some other Python template engines, for the following reasons:

  • Cheetah is not limited to HTML,
  • HTML-style tags are hard to distinguish from real HTML tags,
  • HTML-style tags are not visible in rendered HTML when something goes wrong,
  • HTML-style tags often lead to invalid HTML (e.g., code{<img src="<template*directive>">}),

Cheetah tags are less verbose and easier to understand than HTML-style tags, and HTML-style tags aren't compatible with most WYSIWYG editors. In a WSYWIG editor, Cheetah tags appear to be literal text.

Besides being much more compact, Cheetah also has some advantages over languages that put information inside the HTML tags, such as Zope Page Templates or PHP:

  • HTML or XML-bound languages do not work well with other languages,
  • While ZPT-like syntaxes work well in many ways with WYSIWYG HTML editors, they also give up a significant advantage of those editors -- concrete editing of the document. When logic is hidden away in (largely inaccessible) tags it is hard to understand a page simply by viewing it, and it is hard to confirm or modify that logic.

How stable is Cheetah? How do I upgrade?

Cheetah 2.0 was released [MONTH] [YEAR] with internal restructuring, easier-to-understand usage, updated documentation, and many other improvements. Cheetah 1.0 was released December 2005 after a three-year stable beta. Production sites have been using Cheetah since 2001. Most changes since then have been based on requests from production sites: things they need that we hadn't considered.

Templates and calling code from Cheetah 1.0 remain 100% compatible. Those from pre-1.0 versions since December 2001 (0.9.9) remain compatible except in rare cases.

Important

You must recompile all precompiled templates when upgrading to Cheetah 2.0.

Upgrades from 2.0 to a future version may or may not require recompilation. Try filling a single precompiled template and see if you get a version exception. If you do, recompile them all. Or to be safe on a production site, just recompile them all anyway.

Cheetah's development version is normally as stable as the last release if not better. All CVS checkins are installed and run through the test suite before being checked in.

Additional information is in these files in the Cheetah source distribution:

CHANGES:
All changes in each version.
BUGS:
Known bugs we haven't fixed yet.
TODO:
Enhancements we're planning, thing's like to do someday, and user requests we haven't committed to.

Web site and mailing list

Cheetah releases and other stuff can be obtained from the the Cheetah {bf Web site}: url{http://CheetahTemplate.sourceforge.net}

Cheetah discussions take place on the {bf mailing list} email{cheetahtemplate-discuss@lists.sourceforge.net}. This is where to hear the latest news first.

If you encounter difficulties, or are unsure about how to do something, please post a detailed message to the list. Also please share your experiences, tricks, customizations, and frustrations. And if you have a success story for the "Who Is Using Cheetah" (http://cheetahtemplate.sourceforge.net/whouses.html) or "Testimonials" (http://cheetahtemplate.sourceforge.net/praise.html) page on the website, send it to the mailing list.

Bug reports, patches, and the test suite

If you think there is a bug in Cheetah, send a message to the mailing list with the following information:

  • a description of what you were trying to do and what happened
  • all tracebacks and error output
  • your version of Cheetah
  • your version of Python
  • your operating system
  • whether you have changed anything in the Cheetah installation

Cheetah is packaged with a regression testing suite that is run with each new release to ensure that everything is working as expected and that recent changes haven't broken anything. The test cases are in the Cheetah.Tests module. If you find a reproduceable bug please consider writing a test case that will pass only when the bug is fixed. Send any new test cases to the email list with the subject-line "new test case for Cheetah". (@@MO Shorten paragraph, link to testing section.)